feat(gateway): [EPIC-INT-01A] 拓宽网关 JSON-RPC 协议簇并桥接真实 Runtime 实例#363
Merged
phantom5099 merged 6 commits intoApr 19, 2026
Merged
Conversation
打通 Gateway 到 Runtime 的后端桥梁，为 TUI 下沉隔离铺平道路： 1. 协议扩容：在 JSON-RPC 路由与参数解析层，全量注册 gateway.run, cancel, compact, list, load, resolve 等 6 个运行时核心方法。 2. 权限放行：在 Strict ACL 与 Metrics 白名单中放行上述方法，消灭方法调用时的 403 拦截与 method_not_found 错误。 3. 动态桥接：新建 runtimeBridge 适配器，并在 neocode gateway 启动命令中正式实例化 RuntimePort 注入网关 Server。 4. 契约闭环：在分发层 (bootstrap.go) 完成 RPC 请求向 Runtime 实体方法的映射与转发。
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
发现 3 个需要处理的问题：
resolve_permission目前在分发层被强制要求session_id，与其参数契约不一致，导致无连接绑定场景（尤其 HTTP）请求会被提前拒绝。gateway.run未显式传入run_id时，ACK 回包中的run_id为空，但 runtime 侧会回退到request_id，会造成客户端事件关联不一致。- runtime 错误详情被原样拼接进网关响应，存在内部信息泄露风险。
另外，协议方法已扩容到 6 个 runtime 方法，但文档中的 JSON-RPC 方法表仍停留在旧集合，建议在同一 PR 同步更新文档避免实现/文档漂移。
|
|
||
| // requiresSession 判断指定动作在分发阶段是否必须携带 session_id。 | ||
| func requiresSession(action FrameAction) bool { | ||
| switch action { |
Contributor
There was a problem hiding this comment.
requiresSession 把 FrameActionResolvePermission 也列为必需 session_id。但 gateway.resolvePermission 的参数模型里没有 session_id，且 validateResolvePermissionFrame 也不要求该字段。结果是：在没有连接级 fallback session 的场景（例如典型 HTTP JSON-RPC 请求）会在分发前被 missing required field: session_id 拦截，方法实际上不可用。建议将 resolve_permission 从这里移除，或在协议参数中补齐并明确要求 session_id。
| Action: FrameActionRun, | ||
| RequestID: frame.RequestID, | ||
| SessionID: input.SessionID, | ||
| RunID: input.RunID, |
Contributor
There was a problem hiding this comment.
这里返回的 ACK run_id 直接使用 input.RunID。当调用方不传 run_id 时，bridge 会在 convertGatewayRunInput 内回退到 request_id 提交给 runtime，但 ACK 仍返回空 run_id，客户端后续按 ACK 关联事件会出现不一致。建议在进入 runtime 前统一生成/回填最终 run_id，并在 ACK 中返回该最终值。
| message = "runtime operation" | ||
| } | ||
| if err != nil { | ||
| message = fmt.Sprintf("%s failed: %s", message, strings.TrimSpace(err.Error())) |
Contributor
There was a problem hiding this comment.
runtimeCallFailedFrame 将下游 err.Error() 原样拼接到对外错误消息。对于网络面调用，这可能暴露内部路径、实现细节或底层错误上下文。建议对外返回稳定通用文案（例如 <operation> failed），详细错误仅写入服务端日志。
Collaborator
Author
Role你现在是一位资深的 Go 后端架构师和系统安全专家。你需要对该 PR 进行深度 Code Review。 Task仔细审查给定的 PR 代码变更。本次改动旨在 Gateway 中放行 Review Checkpoints (重点审查清单)
Output Format请以 Markdown 格式输出你的审查报告。要求直奔主题，结构如下：
如果你在某一项中未发现问题，请明确回复“针对 [第 X 项]，代码已安全处理”。 |
Contributor
🛑 安全/稳定性 Blockers
// 在鉴权后注入主体标识（subject）
ctx = WithRequestSubject(ctx, subjectID)
// 在网关转发前强制做所有权校验
if err := runtimePort.AuthorizeSession(ctx, sessionID); err != nil {
return errorFrame(frame, NewFrameError(ErrorCodeAccessDenied, "access denied"))
}
func runtimeCallFailedFrame(frame MessageFrame, err error, operation string) MessageFrame {
code := ErrorCodeInternalError
msg := strings.TrimSpace(operation) + " failed"
if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
code = ErrorCodeInvalidAction
msg = strings.TrimSpace(operation) + " timed out or canceled"
}
// 仅写服务端日志，不把底层 err 细节回传给客户端
return errorFrame(frame, NewFrameError(code, msg))
}
func withRPCDeadline(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) {
if d <= 0 { return ctx, func() {} }
return context.WithTimeout(ctx, d)
}
opCtx, cancel := withRPCDeadline(ctx, gatewayRuntimeTimeout)
defer cancel()
if err := runtimePort.Run(opCtx, input); err != nil { ... }
|
基于 Code Review 的深度反馈，全面加固网关与 Runtime 的桥接链路，修复以下高危与体验缺陷： 1. 逻辑修正：移除 `resolvePermission` 对 `session_id` 的强制前置校验，修复无会话场景下 HTTP 请求被错误拦截的 Bug。 2. 状态一致性：在分发 `gateway.run` 前统一下游 `run_id` 状态，确保 ACK 回包与底层运行时使用的 ID 严格对应，防止客户端后续事件关联断裂。 3. 安全阻断 (信息泄露)：重构错误透传机制，对外彻底屏蔽 `err.Error()` 包含的底层堆栈与敏感细节，仅返回标准化文案，并映射明确的网关错误码（引入稳定的 `timeout`, `invalid_action` 等）。 4. 资源兜底防耗尽：为所有 Runtime 操作（run/compact/load/list 等）增加 30 分钟的硬超时上下文包裹，彻底杜绝下游卡死或异常断连导致的僵尸任务持续占用系统资源。 5. 合规与契约对齐：在会话操作处补充防御 IDOR（越权访问）的安全演进 TODO 声明；同步更新 README 与详细设计文档，彻底对齐扩容后的 JSON-RPC 方法簇与状态码。
Collaborator
Author
|
@xgopilot 请你将codecov/patch的覆盖率提升至百分之九十五以上 |
Contributor
|
已完成本次覆盖率提升并推送到当前 PR 分支。 结果
验证
未完成项：无。 |
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
|
@xgopilot 针对本次PR，请给我一份给AIreview用的提示词，针对的是可能存在的风险点、方案是否合理等等。 |
Contributor
可直接用于 AI Review 的提示词你现在是一名资深 Go 后端架构师 + 网关安全审计专家。请对当前 PR 做深度评审，目标不是语法风格，而是识别高风险缺陷并判断方案是否合理可落地。 请基于以下背景开展评审：
请重点审查以下维度：
输出要求（必须严格遵守）：
附加规则：
说明以上提示词是按这个 PR 的改动面和风险模型定制，可直接粘贴给任意 AI Review 工具使用。 |
Collaborator
|
@xgopilot 你现在是一名资深 Go 后端架构师 + 网关安全审计专家。请对当前 PR 做深度评审，目标不是语法风格，而是识别高风险缺陷并判断方案是否合理可落地。 请基于以下背景开展评审：
请重点审查以下维度：
输出要求（必须严格遵守）：
附加规则：
|
Contributor
🛑 Blockers
|
基于深度安全审计，完成对网关与 Runtime 桥接层的彻底加固与重构，消灭两大 Blocker 级漏洞： 1. IDOR 防护 (Blocker)：引入 SubjectID (主体标识) 机制。鉴权层解析 Token 注入 Subject，并在 loadSession、compact、resolvePermission 等操作前强制执行资源所有权 (Ownership) 校验。彻底阻断多客户端场景下的横向越权。 2. Cancel 全局误杀修复 (Blocker)：废弃无参的全局取消逻辑。强制 `gateway.cancel` 显式提供 `run_id`，在 Runtime 侧通过精准映射表实现点对点任务终止，杜绝并发场景下的横向 DoS 攻击。 3. 异步任务队列优化 (Risk)：重构 `gateway.run` 为标准的 Accepted-ACK 异步模型。网关鉴权后秒回 ACK (含 run_id)，将长耗时的推理任务剥离至独立 goroutine，释放 RPC 阻塞队列，并通过 Stream Relay 推送后续事件流。 4. 严格契约校验 (Risk)：全量启用 `json.Decoder` 的 `DisallowUnknownFields()` 特性，严厉拒绝任何带有拼写错误或未知字段的 JSON-RPC 载荷，提升协议演进安全性。
Collaborator
Author
|
/simplify |
Contributor
处理结果已按 本次先检查了评论日志里的未决 review 点，结论是这 3 条历史问题在当前分支都已修复：
随后调用了 code-simplifier 子代理并吸收低风险简化改动，提交为： 代码简化内容
核心简化：
验证
提交与推送
|
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
Author
|
@xgopilot 请你帮我解决CI未通过的问题以及将覆盖率提升至百分之九十五以上 |
Contributor
处理结果已完成修复并推送到当前 PR 分支： 本次改动
验证
说明：覆盖率阈值以 CI/Codecov 最终计算为准；本次已针对此前低覆盖分支补齐测试点并完成本地回归。 |
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 目标 (Motivation & Context)
本 PR 是 [EPIC-INT-01] 全链路贯通 的第一阶段（Backend Only）。 为了彻底解决 TUI 客户端与 Runtime 底层强耦合的问题，我们必须将 Gateway 作为全系统的唯一通信中枢。本阶段的核心目标是在 Gateway 后端“修路建桥”：放开对应的 RPC 协议通道，更新安全白名单，并将真实的 Runtime 实例正式注入网关引擎中。
目前，我们可以通过 Postman 等工具，携带 Token 成功穿透网关的鉴权与参数校验层，直接唤醒底层的大模型。
Closes #360
✨ 主要变更 (Key Changes)
1. 协议通道扩容 (Protocol Expansion)
jsonrpc.go中新增了对 6 个核心运行时方法的解析与归一化支持：gateway.run,gateway.cancel,gateway.compact,gateway.listSessions,gateway.loadSession,gateway.resolvePermission。2. 安全与观测白名单放行 (Security & Metrics)
security.go中的 Strict ACL 策略，将上述 6 个方法加入合法放行列表，彻底消除method not found和 403 拦截。metrics.go中扩展 method 白名单，防止高基数指标收敛器误杀正常的运行时调用。3. 动态桥接与实例注入 (Runtime Bridge)
gateway_runtime_bridge.go适配器，处理 Gateway 契约与 Runtime 实例的阻抗匹配。gateway_commands.go启动流程：不再传入nil，而是正式实例化RuntimePort并注入到 IPC/Network Server 中。bootstrap.go中完成 RPC handler 的注册分发，实现端到端的流量路由。✅ 验收标准 (Acceptance Criteria)
gateway.run，成功通过 Auth 鉴权和参数强校验，流量精准抵达 Runtime。go test ./...单元测试全量绿灯。go test -race ./...并发竞态检测通过。neocode启动链路（本地直连模式）完全不受影响，无兼容性风险。